Experimental BBS Explossion 3

home *** CD-ROM | disk | FTP | other *** search

/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / gus / demovt15.zip / DEMOVT.DOC < prev next >

Wrap

Text File | 1994-04-26 | 29KB | 650 lines

What it is, and how to use it ───────────────────────────── Let's talk about DemoVT. It's a program that is capable of playing a MOD music while another program is running. If you know what the ShellVT program is, then the DemoVT is a "slightly" modified version. Its primary use is intended for graphics demonstrations (demos) and games, but it could be used for other kinds of applications. It should work on 286 machines, but it has only been tried on 386SX and above. It is NOT a TSR program. Instead, when it is run it loads the music file and then executes another program via the DOS EXEC function. When the executed program terminates, DemoVT terminates also (more on this later). It is NOT a stand alone background modplayer. It requires a minimal (and allows a maximal) collaboration with the executed program. ShellVT is a great stand alone choice if that's what you want ;-) DEMOVT test.mod /f:20000 /d:DMA-SB-Mono /port:$220 /irq:7 /dma:1 /v:74 /sh:test1.exe The above (it should have been just one line) is an example of how to play the TEST.MOD file through the Sound Blaster card at 220-7-1, at a sample rate of 20000 Hz and a volume of 74, while running the TEST1.EXE program. Sample rates range from 4000 to 44100 Hz (it won't get higher than your card allows). Possible devices are: Silence - No sound. Quiet. interprets the music anyway. DMA-SB-Mono - Any Sound Blaster in mono. Also PAS cards. DMA-SB-Stereo - SB Pro and SB 16 in stereo. GUS - Gravis Ultrasound. Fixed rate of 44100 Hz. Port, IRQ and DMA range to any available to your favourite card. You don't want us to list all different possibilities here, do you? Volumes are from 0 to 127. The /sh: program file should have the file extension and the path if necessary. In 'silence' mode, DemoVT will use a serial port for timing (this lets you use the timer 0 for your own purposes). Any serial port is useable, but it will use COM1 by default. To change it, just use the /port: and /irq: options: COM1 - /d:Silence /port:$3F8 /irq:4 COM2 - /d:Silence /port:$2F8 /irq:3 COM3 - /d:Silence /port:$3E8 /irq:4 COM4 - /d:Silence /port:$2E8 /irq:3 IRQ values for COM3 and COM4 are usually changed to any other. COM2 to COM4 may be absent, but DemoVT will not detect this and will hang. DemoVT script files ─────────────────── Above we said that DemoVT finishes when the executed program terminates. That's not completely true. In fact, it's possible to keep the DemoVT running after that. How? Using scripts to make the DemoVT load a (possibly) different MOD and/or run another (possibly) different program. If you did this by executing repeatedly DemoVT, the sound card would get initialised each time, thus making an awful click. Create a text file with this: ; -------------- Start of TEST.VTO -------------------- /f:44100 ; 44100 Hz /d:DMA-SB-Stereo ; Stereo Sound Blaster. /port:$220 ; Sound Blaster Port. /irq:7 ; Sound Blaster IRQ. /dma:1 ; Sound Blaster DMA. /v:127 ; Sound volume. test1.mod /sh:test1.exe ; 1st MOD & 1st program. / /v:74 test2.mod /sh:test2.exe ; 2nd MOD & 2nd program. ; Volume of 127 ; --------------- End of TEST.VTO --------------------- Note the "/" at the start of the second MOD/Program. It's required to make the first ones to be executed. It separates the different execution lines. Also, it's important to make /sh: the last switch in the line. You can add a full command line to the program if you want. And you can really add comments starting with ";". The above script would be used executing: DEMOVT @test.vto For those of you who have seen it, the Inconexia Demo by Iguana generates a script like the above, bigger, with an executable file for each part. If you want to run several programs under a unique MOD, like different parts of a trackmo, just specify the MOD file only with the first executable. As an example, here's included the VTO that runs the whole Inconexia demo: ; --------------- End of INCONEXI.VTO --------------------- /d:gus ; Use the Gravis Ultrasound. /port:$240 ; GUS Port. /irq:11 ; GUS Irq. /v:80 ; Initial volume. inconexi.003 /sh:inconexi.004 / inconexi.005 /sh:inconexi.006 / inconexi.008 /sh:inconexi.009 / /sh:inconexi.010 / /sh:inconexi.011 / /sh:inconexi.012 / /sh:inconexi.013 / inconexi.014 /v:128 /sh:inconexi.015 ; --------------- End of INCONEXI.VTO --------------------- Advanced options ──────────────── To play the MOD from a different sequence position (i.e. 14), use the following switch: /ss:14 Also, use the switches /sl:22 and /sr:18 to load only the sequence up to position 22 and to repeat from position 18. All values range from 1 to 128. Experiment with this. If you want to have the MOD file stored inside a bigger file, you can use the switch /off:193847. This will load the MOD from position 193847 in the file. Also, experiment with it. Synchronisation ─────────────── This is the big thing in DemoVT that makes it very special. It's also very tricky, so we advice you to read all this very carefully and look into the examples. And, of course, to experiment a lot with it. The first thing to talk about is the delay. When DemoVT interprets the MOD's partiture, it does it half a second ahead of the sound it generates. The important thing is to always remember this delay when interacting with the music (changing the volume or jumping in the partiture). DemoVT will hide this delay when it tells you about its state, but you will have to keep it in mind when you try to alter DemoVT's state. The first way to synchronize is using semaphores. There's an array of 256 semaphores; each of them gets incremented whenever a command number 8 is found in any channel of the MOD. The parameter of this command tells which one of the 256 semaphores gets incremented. Your program can check any semaphore anytime for a given value, to see if the music has passed through a point in the partiture. When DemoVT is started, all semaphores are set to zero. The second way to synchronize is using precise timing. The DemoVT provides you with a counter that gets incremented 50 times per second, and which is also used for the MOD timing. You can read it and therefore know exactly how much time has passed since the music started. DemoVT also lets you control exactly when does the music start. In fact, DemoVT doesn't start playing until you explicitly tell. Modes of operation ────────────────── DemoVT can operate in Poll Mode or Timer Mode. When DemoVT starts it is in Poll Mode. Read below for more information. Ok! What else? ────────────── Now that I've got you interested, I'll tell you a couple of things. This is what I expect from you: First, if you use this, you MUST credit me: JCAB of VangeliSTeam/Iguana. Second, if you have used DemoVT for non-profitable non-commercial purposes, please contact me at the address below and tell me what you used it for, and how you did it. If possible, send me a copy of the program or whatever you have made using the DemoVT. You'll be sent greetings in the following releases. Third, if you're going to use it for a commercial and/or profitable purpose, you must first contact me to get a written permission. You could also use it without paying, contacting nor crediting me. If you do so then fuck you. If you find this program worth it, you can send a contribution of $10, or anything you feel is fair, to the address below. You are also encouraged to send any comments about anything you want concerning the program and/or documentation, or questions about your particular use of DemoVT. Please, enclose a self-addressed, stamped envelope if you expect an answer. It would be very encouraging to receive feedback about my work. This program is Copyrighted by Juan Carlos Arévalo Baeza, aka VangeliSTeam, and is thus protected by copyright laws. It is not public domain; it can be freely distributed, but can only be used under the conditions stated above. DISCLAIMER: This document is just the description of what I use this program for, and how I do it. It's enough for me, but I give no kind of warranty about the way it behaves, and won't be liable for any kind of damages it could cause to anybody else. CONTACT ADDRESS: ┌──────────────────────────┐ │ Juan Carlos Arévalo │ │ Apdo. de Correos 156.405 │ │ 28080 - Madrid │ │ Spain │ └──────────────────────────┘ Also, electronically: Fidonet: 2:341/27.16 CDNet: 94:620/200.1 SoundNet: 34:2000/200.16 Internet: jcarlos@gw.iic.uam.es jarevalo@dit.upm.es (more reliable) a880104@zipi.fi.upm.es (Jare's) You can also login to any of these Bulletin Board Systems and leave a message to the sysop: ╒═════════════════════╤═══════════╤═══════════════╤════════════╕ │BBS name │Country │Phone # │Sysop │ ╞═════════════════════╪═══════════╪═══════════════╪════════════╡ │BlasterSound (Iguana │Spain │+34-58-293-583 │Mikel │ │World Headquarters) │ │ │ │ ├─────────────────────┼───────────┼───────────────┼────────────┤ │Deckard (VangeliSTeam│Spain │+34-1-643-10-67│Pedro de Paz│ │World Headquarters) │ │ │ │ ╘═════════════════════╧═══════════╧═══════════════╧════════════╛ Technical information ───────────────────── This program is heavily based on the Public Domain utility called VangeliSTracker, also made by me. The last version up to date of VangeliSTracker is 1.39, and its source code is also in the Public Domain, so you can find many technical insights of DemoVT in it. When using the Silence "output device", the timing is done by using the COM1 serial port and IRQ 4. It might have problems with some mouse drivers. I know it's wicked, but that's the way it's made. When using sound output through the GUS card, the internal timers of this card are used, and the partiture gets interpreted only through interrupts. Anyway, the Timer and Polled modes are emulated. No DMA is used. The instrument data is kept in the card's memory. It's up to you to make sure there's enough of that memory. When using Sound Blaster, the DMA provides the timing. It also takes up more memory because of the DMA buffers involved, and the instruments of the MOD are kept in main memory and UMB memory. In Timer mode, only INT 1Ch (must be called a minimum of 12.5 times per second) is used, and the timer hardware is not reprogrammed. Libraries provided ────────────────── The DemoVT is designed to be used through a few routines we provide in the libraries. They are provided for Real Mode Assembler, PMode Assembler (Tran's PMode), Turbo Pascal, Real Mode C and DPMI (Watcom) C. Here you can find the descriptions of those routines. The names used are those of the assembler interface. To know about the other interfaces (C and PAS), please, look into the interface source code and into the examples provided. -------------------------------- InitMusic Call this if you want to mess with the DemoVT. I suppose you want to. It detects whether DemoVT is present (DL = 1) or not (DL = 0), and initalizes the above pointers. -------------------------------- CallMusic Calls the player when in polled mode. This means that if you want to use the timer (IRQ 0) for your application, you must manually call the DemoVT so that it will play the partiture. This routine must be called at least at a 50Hz average rate; if you don't, the music will jump. You can call it several times before making a long process; experiment how many times you need to avoid jumps. -------------------------------- VTConnectTimer Turn on timer mode. In this mode the player uses the system timer to perform its task, so you don't need to manually call InitMusic. But you also can't use the timer for you. Please don't hook to the IRQ0 and then call the old handler (DemoVT's), if you want to do such a thing use the polled mode. -------------------------------- VTDisconnectTimer Enter polled mode. From now on, make frequent calls to CallMusic, and feel free to do what you desire with the IRQ0 timer. -------------------------------- VTGetTickCounter Reads the internal 50Hz counter of the DemoVT into DX:AX. Use this to synchronize with the music in terms of time played. (For synchronization you can also use the semaphores described later.) -------------------------------- VTBeginSync Performs the usual preparations for calling the next routines. Call this when you want to be a bit in sync with the music. If you just want a background music you won't need this, but I'd advise you to call it anyway 'cause I'm not sure of the behaviour (I ALWAYS call it). -------------------------------- VTWaitForStart Performs a half-second wait and initializes the tick counter to zero. In the DemoVT, the music always goes half a second behind the partiture; this means that, for example, a volume change will take effect that half second later. Use this routine to prepare yourself for that change. Another place where you will want to use this is at the start of a song. Right after calling VTBeginSync, there will be no music; call VTWaitForStart, and it will return at the precise moment when the first note of the song is starting to fill your ears. -------------------------------- VTJumpPos Jump to some precise pattern in the sequence (AH) , and to a note inside that pattern (AL). Both values range from 1 to whatever. Remeber this, FastTracker musicians! The jump will take effect half a second after you call this. -------------------------------- VTCheckSemaphore Compares AL with the value of the semaphore number 'BX'. Sempahore values are incremented by a special command embedded in the MOD: Command number 8. The parameter of this command gives the number of the semaphore to increment. -------------------------------- VTSetSemaphore Sets the value of the semaphore # BX to the value AL. You'll find this useful to clear the value of a semaphore that gets set by a command in a pattern that repeats several times. Huuhh... when you need this you will know, I guess. -------------------------------- VTMiddleSync Checks if the sempahore # BX is set. If not, it jumps to the position DH, DL (pattern, note) in the MOD. In any case, it waits for the next semaphore (BX +1) to activate and exists without jumping. You can use this to set precise synchronization points. When you want to get to one (for example, when starting some part of a trackmo), you want to wait for that time to come, or get back to it if it already passed (by some slow disk reading or something like that). We used this to allow you to skip parts of the Inconexia trackmo and keep the music synchronized. It's hard to explain; read the above description and keep it in mind when you need something like this. -------------------------------- VTSetSoundVolume Changes the sound's volume to AL. It will really change 1/2 second after this call. You don't have to worry about the delay when you use this to fade the music. Just wait half a second after you finish fading. -------------------------------- VTGetSoundVolume Reads the sound's volume into AL. Fairly straightforward, ain't it? Software interface ────────────────── If you are so nice that you refuse to use our wonderful library, then you can try to access the DemoVT directly. Good luck. To access the DemoVT from your program, you must first call the Multiplex Interrupt DOS service (INT 2Fh). The appropriate setup calling sequence in assembler is the following: MagicAX = 5654h; {'VT'} MagicBX = 5472h; {'Tr'} MagicCX = 6163h; {'ac'} MagicXorBX = 6B65h; {'ke'} MagicXorCX = 7220h; {'r '} MOV AX,MagicAX MOV BX,MagicBX MOV CX,MagicCX XOR DI,DI MOV ES,DI INT 2Fh XOR DL,DL AND AX,AX JNZ @@no CMP BX,MagicBX XOR MagicXorBX JNZ @@no CMP CX,MagicCX XOR MagicXorCX JNZ @@no INC DL @@no: After this, register DL will contain a 1 if the DemoVT is in fact installed, or a 0 if it is not. If the DemoVT is installed, then ES:DI will contain a far pointer to a character string in Pascal format (length byte first) describing the DemoVT program and version. Also, in ES:[DI-4] is a far pointer to a data structure that contains adittional data. Here is a description of the data found under this pointer: ; These are modified by DemoVT, and you can read them. Semaphores DB 256 DUP(?) ; Array of semaphores. You can read or ; modify them (usually cleaning them). ChansTrig DB 32 DUP(?) ; == 1 -> channel retriggered a note. NumChannels DB ? ; Number of channels in the MOD. CtrlEntryPoint DD ? ; Address of ther DemoVT service proc. TickCounter DD ? ; This one provides some form for you ; to do timing, incremented at 50Hz. RegEntryPoint DD ? ; DVT Service taking parm in AX. ChansData TChanData 32 DUP (<>) ; Per-channel info. Note DB ? ; Note in the current pattern. Seq DB ? ; Number of playing pattern. DB 81 DUP(?) ; Reserved. ; These are supposed to be modified by you ; to tell DemoVT your intentions. :) DB ? ; Reserved. DW ? ; Reserved. JumpNewPos DB ? ; Indicates that you want to jump to ; another position inside the MOD. JumpPosSeq DB ? ; Sequence position to jump to. JumpPosNote DB ? ; Note inside the pattern to jump to. SoundVolume DB ? ; Put your favourite volume here. ; You can perform fades and the like. ; 0-255. Abort DB ? ; Set to 1 to force DVT to exit after ; your program exits. DB 248 DUP(?) ; Reserved. The structure TChanData is: TChanData STRUC Period DW ? Ins DB ? Vol DB ? ENDS Variable descriptions are as follows: ========== Semaphores ========== Everytime DemoVT finds a command 8 in the MOD file, it increments one of the bytes in this variable. The parameter of the command says which of the bytes is incremented. You can use the semaphores to synchronize your program to the music being played. For more information, see the chapter "Synchronisation". ========= ChansTrig ========= Those variables are set to 1 when the corresponding MOD channel retriggers a note. You should set it to 0 when you read it. With this, you can implement channel non-volume bars. It is updated with the real sound, not the half a second delay. =========== NumChannels =========== This is the number of channels that the MOD contains. ============== CtrlEntryPoint ============== This variable contains a pointer to the routine that provides the DemoVT services. Service number must be pushed on the stack, and none of the services requires parameters. This routine can be called directly from Turbo Pascal. If you are using the C language, then you must declare this routine as "FAR PASCAL". Service numbers are: Service 0: Start Timer mode, using the system timer. After calling this routine, music keeps running automaticly. You must use this when you're not sure if you will be able to call service 2 often enough (i.e. when reading files using DOS's INT 21h). Service 1: Start Poll mode. Just the opposite of service 0. DemoVT always starts in Poll mode. Poll mode is a better choice when you need a fine timing and/or need to synchronize to the video retrace, which mostly happens in demos and games. Service 2: Call the song routine when in Poll mode. Must be called more than 50 times per second, unless you're using Timer mode (service 0). This keeps the music running. Service 3: Begin synchronization. You should call this before the music starts playing. It resets everything to make it an exact half a second wait before the sound starts coming out. =========== TickCounter =========== This variable gets incremented by DemoVT 50 times per second. It's intended for you, to get a steady timing method, so you can synchronize correctly with the music. ============= RegEntryPoint ============= This is the same as the CtrlEntryPoint above, only that the service number is given in the AX register. This is needed for DPMI interfaces. ========= ChansData ========= This gives information on the period (the note), the volume and the instrument being played on each channel. ==== Note Seq ==== This tells you the current position/note in the partiture that is being played right now. Sequence positions and notes are always 1-based in DemoVT. Sequence ranges from 1 to 128 and notes from 1 to 64. =========== JumpNewPos JumpPosSeq JumpPosNote =========== Those three variables are used to jump in the music. You are supposed to know that MOD music is made out of patterns of 64 notes each, and that patterns are arranged in a sequence of pattern numbers. Well, maybe you use different names for those, but you'll understand. To force a jump in the music, you put the desired sequence position in JumpPosSeq, the desired note of the pattern in JumpPosNote, and then a 1 in JumpNewPos. The music will automaticly jump to that position (well, half a second later ;-D). Sequence positions and notes are always 1-based in DemoVT. Sequence ranges from 1 to 128 and notes from 1 to 64. =========== SoundVolume =========== You can change this to whatever volume you want the music to use. It ranges from 0 to 255, and the default volume is 255 (maximum). This does not correspond to the /v: switch of the DemoVT program. Sound volume ALWAYS ranges from 0 to 255, with 255 corresponding to the /v: volume. This change will take effect half a second later. ===== Abort ===== Set this to 1 if you want DemoVT to exit to DOS as soon as your program does, without playing any more MODs nor executing any more programs. This is used to abort a demo when the user presses ESC. ========= reservedX ========= Those are unused variables. Don't mangle with them or maybe your wonderful program won't work with future versions of DemoVT that support MegaBlasterSuperUltraSound WOWWHATCARD. <Geeezz. I sound like Mikrozoft> <<At least I didn't call it "undocumented">> Madrid, 17th of April, 1993.